home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / cat3 / CrtMainWin.3 < prev    next >
Text File  |  1994-09-20  |  14KB  |  331 lines

  1.  
  2.  
  3.  
  4. Tk_CreateMainWindow(3)Tk Library Procedures
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NAME
  11.      Tk_CreateMainWindow,                        Tk_CreateWindow,
  12.      Tk_CreateWindowFromPath,                   Tk_DestroyWindow,
  13.      Tk_MakeWindowExist - create or delete window
  14.  
  15. SYNOPSIS
  16.      #include <tk.h>
  17.  
  18.      Tk_Window
  19.      Tk_CreateMainWindow(_i_n_t_e_r_p, _s_c_r_e_e_n_N_a_m_e, _b_a_s_e_N_a_m_e, _c_l_a_s_s_N_a_m_e)  |
  20.  
  21.      Tk_Window
  22.      Tk_CreateWindow(_i_n_t_e_r_p, _p_a_r_e_n_t, _n_a_m_e, _t_o_p_L_e_v_S_c_r_e_e_n)
  23.  
  24.      Tk_Window
  25.      Tk_CreateWindowFromPath(_i_n_t_e_r_p, _t_k_w_i_n, _p_a_t_h_N_a_m_e, _t_o_p_L_e_v_S_c_r_e_e_n)
  26.  
  27.      Tk_DestroyWindow(_t_k_w_i_n)
  28.  
  29.      Tk_MakeWindowExist(_t_k_w_i_n)
  30.  
  31. ARGUMENTS
  32.      Tcl_Interp   *_i_n_t_e_r_p         (out)     Tcl  interpreter   to
  33.                                             use for error report-
  34.                                             ing.   If  no   error
  35.                                             occurs,  then *_i_n_t_e_r_p
  36.                                             isn't modified.   For
  37.                                             Tk_CreateMainWindow,
  38.                                             this  interpreter  is
  39.                                             associated       per-
  40.                                             manently   with   the
  41.                                             created  window,  and
  42.                                             Tk-related   commands
  43.                                             are  bound  into  the
  44.                                             interpreter.
  45.  
  46.      char         *_s_c_r_e_e_n_N_a_m_e     (in)      String name of screen
  47.                                             on  which  to  create
  48.                                             window.  Has the form
  49.                                             _d_i_s_p_l_a_y_N_a_m_e._s_c_r_e_e_n_N_u_m,
  50.                                             where _d_i_s_p_l_a_y_N_a_m_e  is
  51.                                             the name of a display
  52.                                             and  _s_c_r_e_e_n_N_u_m  is  a
  53.                                             screen   number.   If
  54.                                             the dot and _s_c_r_e_e_n_N_u_m
  55.                                             are    omitted,   the
  56.                                             screen         number
  57.                                             defaults  to  0.   If
  58.                                             _s_c_r_e_e_n_N_a_m_e is NULL or
  59.                                             empty         string,
  60.  
  61.  
  62.  
  63. Tk                                                              1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. Tk_CreateMainWindow(3)Tk Library Procedures
  71.  
  72.  
  73.  
  74.                                             defaults to  contents
  75.                                             of  DISPLAY  environ-
  76.                                             ment variable.
  77.  
  78.      char         *_b_a_s_e_N_a_m_e       (in)      Name to use for  this
  79.                                             main   window.    See
  80.                                             below for details.
  81.  
  82.      char         *_c_l_a_s_s_N_a_m_e      (in)      Class  to   use   for  |
  83.                                             application  and  for  |
  84.                                             main window.
  85.  
  86.      Tk_Window    _p_a_r_e_n_t          (in)      Token for the  window
  87.                                             that  is  to serve as
  88.                                             the logical parent of
  89.                                             the new window.
  90.  
  91.      char         *_n_a_m_e           (in)      Name to use for  this
  92.                                             window.     Must   be
  93.                                             unique   among    all
  94.                                             children  of the same
  95.                                             _p_a_r_e_n_t.
  96.  
  97.      char         *_t_o_p_L_e_v_S_c_r_e_e_n   (in)      Has  same  format  as
  98.                                             _s_c_r_e_e_n_N_a_m_e.  If NULL,
  99.                                             then  new  window  is
  100.                                             created  as an inter-
  101.                                             nal window.  If  non-
  102.                                             NULL,  new  window is
  103.                                             created  as  a   top-
  104.                                             level    window    on
  105.                                             screen  _t_o_p_L_e_v_S_c_r_e_e_n.
  106.                                             If _t_o_p_L_e_v_S_c_r_e_e_n is an
  107.                                             empty  string  (``'')
  108.                                             then  new  window  is
  109.                                             created as  top-level
  110.                                             window   of  _p_a_r_e_n_t's
  111.                                             screen.
  112.  
  113.      Tk_Window    _t_k_w_i_n           (in)      Token for window.
  114.  
  115.      char         *_p_a_t_h_N_a_m_e       (in)      Name of  new  window,
  116.                                             specified   as   path
  117.                                             name within  applica-
  118.                                             tion (e.g. .a.b.c).
  119. _________________________________________________________________
  120.  
  121.  
  122. DESCRIPTION
  123.      The three procedures  Tk_CreateMainWindow,  Tk_CreateWindow,
  124.      and  Tk_CreateWindowFromPath  are used to create new windows
  125.      for use in Tk-based applications.  Each  of  the  procedures
  126.  
  127.  
  128.  
  129. Tk                                                              2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. Tk_CreateMainWindow(3)Tk Library Procedures
  137.  
  138.  
  139.  
  140.      returns a token that can be used to manipulate the window in
  141.      other calls to the Tk library.  If the  window  couldn't  be
  142.      created  successfully,  then  NULL  is  returned and _i_n_t_e_r_p-
  143.      >_r_e_s_u_l_t is modified to hold an error message.
  144.  
  145.      Tk supports three different kinds of windows:  main windows,
  146.      internal  windows,  and top-level windows.  A main window is
  147.      the outermost window corresponding to an application.   Main
  148.      windows  correspond  to the independent units of an applica-
  149.      tion, such as a view on a file that is part of an editor, or
  150.      a  clock,  or a terminal emulator.  A main window is created
  151.      as a child of the root window of the screen indicated by the
  152.      _s_c_r_e_e_n_N_a_m_e.   Each main window, and all its descendants, are
  153.      typically associated with a single Tcl command  interpreter.
  154.      An  internal  window  is an interior window of a Tk applica-
  155.      tion, such as a scrollbar or menu bar  or  button.   A  top-
  156.      level window is one that is created as a child of a screen's
  157.      root window, rather than as an interior window, but which is
  158.      logically  part  of  some existing main window.  Examples of
  159.      top-level windows are pop-up menus and dialog boxes.
  160.  
  161.      Tk_CreateMainWindow creates a new main window and associates  |
  162.      its  _i_n_t_e_r_p  argument  with that window and all its eventual  |
  163.      descendants.  Tk_CreateMainWindow also carries  out  several  |
  164.      other actions to set up the new application.  First, it adds  |
  165.      all the Tk commands to those  already  defined  for  _i_n_t_e_r_p.  |
  166.      Second,  it  turns  the  new  window into a toplevel widget,  |
  167.      which will cause the X window to be created  and  mapped  as  |
  168.      soon    as    the    application    goes    idle.     Third,  |
  169.      Tk_CreateMainWindow registers  _i_n_t_e_r_p  so  that  it  can  be
  170.      accessed  remotely  by  other Tk applications using the send
  171.      command and the name _b_a_s_e_N_a_m_e.  Normally, _b_a_s_e_N_a_m_e  consists
  172.      of  the  name  of the application followed by a space and an
  173.      identifier for this particular main window (if such an iden-
  174.      tifier  is  relevant).   For  example,  an  editor  named mx
  175.      displaying the file foo.c would  use  ``mx  foo.c''  as  the
  176.      basename.  An application that doesn't usually have multiple
  177.      instances, such as a clock program, would just use the  name
  178.      of the application, e.g. ``xclock''.  If _b_a_s_e_N_a_m_e is already
  179.      in  use  by  some   other   registered   interpreter,   then
  180.      Tk_CreateMainWindow  extends  _b_a_s_e_N_a_m_e with a number to pro-
  181.      duce a unique name like ``mx foo.c #2'' or  ``xclock  #12''.
  182.      This  name  is used both as the name of the window (returned
  183.      by Tk_Name) and as the registered name of  the  interpreter.  |
  184.      Fourth,  Tk_CreateMainWindow  sets _c_l_a_s_s_N_a_m_e as the class of  |
  185.      the application (among other things, this is used for  look-  |
  186.      ups  in  the  option database), and also as the class of the  |
  187.      main widget.
  188.  
  189.      Either internal or top-level windows may be created by  cal-
  190.      ling Tk_CreateWindow.  If the _t_o_p_L_e_v_S_c_r_e_e_n argument is NULL,
  191.      then  the  new  window  will  be  an  internal  window.   If
  192.  
  193.  
  194.  
  195. Tk                                                              3
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. Tk_CreateMainWindow(3)Tk Library Procedures
  203.  
  204.  
  205.  
  206.      _t_o_p_L_e_v_S_c_r_e_e_n  is  non-NULL,  then  the  new window will be a
  207.      top-level window:  _t_o_p_L_e_v_S_c_r_e_e_n  indicates  the  name  of  a
  208.      screen  and the new window will be created as a child of the
  209.      root window of _t_o_p_L_e_v_S_c_r_e_e_n.  In either case  Tk  will  con-
  210.      sider  the new window to be the logical child of _p_a_r_e_n_t: the
  211.      new window's path name will reflect this fact,  options  may
  212.      be  specified  for the new window under this assumption, and
  213.      so on.  The only difference is that new X window for a  top-
  214.      level  window will not be a child of _p_a_r_e_n_t's X window.  For
  215.      example, a pull-down menu's _p_a_r_e_n_t would be the  button-like
  216.      window  used to invoke it, which would in turn be a child of
  217.      the  menu  bar  window.   A  dialog  box  might   have   the
  218.      application's  main  window  as  its  parent.  This approach
  219.      means that all the windows of an  application  fall  into  a
  220.      hierarchical  arrangement  with  a single logical root:  the
  221.      application's main window.
  222.  
  223.      Tk_CreateWindowFromPath offers an alternate way of  specify-
  224.      ing  new windows.  In Tk_CreateWindowFromPath the new window
  225.      is specified with a token  for  any  window  in  the  target
  226.      application  (_t_k_w_i_n),  plus  a path name for the new window.
  227.      It produces the same effect as  Tk_CreateWindow  and  allows
  228.      both top-level and internal windows to be created, depending
  229.      on   the   value   of    _t_o_p_L_e_v_S_c_r_e_e_n.     In    calls    to
  230.      Tk_CreateWindowFromPath, as in calls to Tk_CreateWindow, the
  231.      parent of the new window must exist at the time of the call,
  232.      but the new window must not already exist.
  233.  
  234.      In truth,  the  window-creation  procedures  don't  actually
  235.      issue  the  command  to X to create a window.  Instead, they
  236.      create a local data structure associated with the window and
  237.      defer  the  creation of the X window.  The window will actu-
  238.      ally be created by the first call to Tk_MapWindow.  Deferred
  239.      window  creation  allows various aspects of the window (such
  240.      as its size, background color, etc.) to  be  modified  after
  241.      its creation without incurring any overhead in the X server.
  242.      When the window is finally mapped all of the  window  attri-
  243.      butes can be set while creating the window.
  244.  
  245.      The value returned by a window-creation procedure is not the
  246.      X  token  for  the  window (it can't be, since X hasn't been
  247.      asked to create the window yet).  Instead, it is a token for
  248.      Tk's  local  data  structure for the window.  Most of the Tk
  249.      library procedures take  Tk_Window  tokens,  rather  than  X
  250.      identifiers.    The   actual  X  window  identifier  can  be
  251.      retrieved  from  the  local   data   structure   using   the
  252.      Tk_WindowId macro;  see the manual entry for Tk_WindowId for
  253.      details.
  254.  
  255.      Tk_DestroyWindow deletes a window and all the data strutures
  256.      associated  with  it,  including  any event handlers created
  257.      with Tk_CreateEventHandler.  In  addition,  Tk_DestroyWindow
  258.  
  259.  
  260.  
  261. Tk                                                              4
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. Tk_CreateMainWindow(3)Tk Library Procedures
  269.  
  270.  
  271.  
  272.      will  delete  any children of _t_k_w_i_n recursively (where chil-
  273.      dren are defined in the Tk sense, consisting of all  windows
  274.      that  were  created  with  the  given window as _p_a_r_e_n_t).  If
  275.      _t_k_w_i_n was  created  by  Tk_CreateInternalWindow  then  event
  276.      handlers  interested  in  destroy events are invoked immedi-
  277.      ately.  If _t_k_w_i_n is a top-level or  main  window,  then  the
  278.      event  handlers  will be invoked later, after X has seen the
  279.      request and returned an event for it.
  280.  
  281.      If a window has been created but hasn't been mapped, so no X
  282.      window exists, it is possible to force the creation of the X
  283.      window by calling Tk_MakeWindowExist.  This procedure issues
  284.      the X commands to instantiate the window given by _t_k_w_i_n.
  285.  
  286.  
  287. KEYWORDS
  288.      create, deferred creation, destroy, display,  internal  win-
  289.      dow, main window, register, screen, top-level window, window
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327. Tk                                                              5
  328.  
  329.  
  330.  
  331.